The file SWSounds.c in the SpriteWorld Files->Utils folder contains some easy to use routines for playing asynchronous sounds. If you need anything more elaborate, your should use some other library for your sounds, such as the Hollywood Sound Library included with the Tricks of the Mac Game Programming Gurus book, or the Caveman Sound System, a free sound library available for download on the internet. Even so, SWSounds.c contains several features often found only in "advanced" sound kits, all while being very easy to use.
To use the routines, just add SWSounds.c to your project, and #include SWSounds.h in your source. At the beginning of your program, call IsNewSoundManagerInstalled to ensure that Sound Manager 3.0 is installed. Then call CreateSoundChannels and LoadSounds. You are then ready to call PlaySound or PlaySound2 to play any of the sounds you have loaded. When your program is ready to quit, you should call DisposeSoundChannels and optionally DisposeSounds. DisposeSoundChannels will stop any sounds currently playing when it is called.
Some "advanced" parameters are provided by the PlaySound2 function. This function allows you to adjust the sound's initial volume and stereo position. You may also change a sound's volume and stereo position while it is playing by using the FindSound function to find the channel the sound is playing in, and then calling SetChannelVolume or SetStereoPosition. There are also routines for saving, setting, and restoring the system volume.
Function Reference
IsNewSoundManagerInstalled
Boolean IsNewSoundManagerInstalled( void )
Call this function when your program is first starting up to determine if Sound Manager 3.0 or later is installed. Sound Manager 3.0 is required for SWSounds.c to function. If version 3.0 or later is available, this function will return true; otherwise it will return false.
SetSystemVolume
void SetSystemVolume(short volume)
This function sets the system sound volume. The volume parameter should be a value between 0 and 7, where 0 is silence and 7 is maximum volume. If your program uses this function, you should call SaveSystemVolume when your application first starts up, and then RestoreSystemVolume when it quits.
Note: Macintosh sound hardware is actually capable of 255 different audio levels, not just 7. If you need this fine control over the system sound level, you can call SetDefaultOutputVolume instead of SetSystemVolume. SetSystemVolume is intended to make it easy for you to provide the user with a menu of volumes 0-7, where they can set the sound volume just like they do in the Control Panel.
GetSystemVolume
void GetSystemVolume(short *volume)
This function returns the current system volume in the volume parameter, which will be a value between 0 and 7.
SaveSystemVolume
void SaveSystemVolume( void )
If your application uses SetSystemVolume, you should call SaveSystemVolume when your application first starts up, and then RestoreSystemVolume when it quits. It is also recommended that you call RestoreSystemVolume if your application goes into the background, and then SaveSystemVolume again when it gets switched back, since the volume may have been changed while it was switched out. You may then wish to call SetSystemVolume to restore the volume to your game's previous settings before it went into the background.
RestoreSystemVolume
void RestoreSystemVolume( void )
Call this when your program quits to restore the system volume to its original value when you called SaveSystemVolume.
CreateSoundChannels
OSErr CreateSoundChannels(short numChannels)
Call this routine at the beginning of your program to create the sound channels needed by PlaySound. The more channels you have, the more sounds you can play at once, but having lots of sounds playing simultaneously can slow the program down on slower computers. Four sound channels is what many programmers use.
An error code is returned if the numChannels parameter is less than 1, or if there was not enough memory to create the sound channels.
DisposeSoundChannels
void DisposeSoundChannels( void )
Call this at the end of your program to dispose of the sound channels you created with CreateSoundChannels. Any sounds currently playing in those channels will be stopped.
LoadSounds
OSErr LoadSounds(short startResID, short numSounds )
This function loads the 'snd ' resources into memory and locks them so they can be played with the PlaySound function. The startResID parameter specifies the first snd resource to be loaded, and numSounds specifies how many sounds you wish to load. So if you pass 128 as your startResID, and 5 as your numSounds, resources 128-132 will be loaded.
An error code will be returned if any of the resources could not be found, or if there was not enough memory to load them. Note that it is safe to continue your program even if this function returns an error code. PlaySound will simply not play any sounds that weren't loaded. This means that your users could remove certain sounds from the program if they don't want those sounds to be played. If you don't like that idea, make your program quit if this function returns an error code of type resNotFound, since that means some of the sound resources are missing from your program. (It should probably quit no matter what if any other error code is returned, since that means there wasn't enough memory to load the sounds.)
DisposeSounds
void DisposeSounds( void )
Call this to dispose the sounded loaded by LoadSounds(). If you wish, you may call DisposeSounds and then LoadSounds again if you want to load new sounds for a different level. However, the more typical practice is to load all of your sounds at the beginning of the program, and dispose them all at the end.
It isn't necessary to call this function if your program is about to quit, since the heap will be cleaned up automatically anyway.
PlaySound
void PlaySound(short soundID, short channelNum, PlayType playType)
This function will play the specified sound according to the instructions specified by the playType parameter. The soundID is a number indicating the sound you wish played; 0 is the first sound loaded, 1 is the second, and so on. The channelNum is a number indicating the channel you wish the sound played in; 0 is the first channel, 1 the second, etc.
The playType is one of the following three definitions:
kFindEmptyChannel - Plays the sound in an empty channel if possible, with channelNum given first priority. If none are available, it searches for the same sound already playing and replaces it, otherwise it plays the sound in the channel specified by channelNum, replacing the sound that was previously playing in that channel.
kReplaceSameSound - Searches all the channels, starting the new sound in a channel that was already playing the same sound if there is one. If the same sound was not already playing anywhere, this command behaves the same as kFindEmptyChannel.
kPlaySoundInChannel - Plays the sound in the channel specified by channelNum, stopping any sound that was previously playing in that channel.
This function is basically a simplified version of PlaySound2. Although it doesn't have volume or stereoPosition parameters, the volume is automatically set to 256 and the stereoPosition is set to 0 (center). You should call PlaySound2 if you wish control over these values.
PlaySound2
void PlaySound2(
short soundID,
short channelNum,
PlayType playType,
short volume,
short stereoPosition,
UnsignedFixed rate,
Boolean doLoopingSound)
This function is identical to PlaySound except that it gives you more control over the sound; you can now set the sound's initial volume and stereoPosition. The rate and doLoopingSound parameters are currently not implemented; that are in this function so that if I do add them in the future, you won't have to change your source code. Until then, you should pass false as the doLoopingSound parameter, and k22khz as the rate parameter. k22khz is defined in SWSounds.h.
The soundID, channelNum, and playType are the same as you would pass to PlaySound. As for the volume and stereoPosition, see SetChannelVolume and SetStereoPosition for descriptions of those parameters. Basically, volume should be a value between 0 and 256, where 0 is silence and 256 is full or normal volume, and stereoPosition should be a value between -256 and 256, where -256 is full left, 256 is full right, and 0 is smack dab in the middle.
StopSound
void StopSound(short soundID)
This function searches all channels for soundID, and if it finds any channel currently playing that sound, it stops it. There really won't be much use for this function until I add looping sounds. At that time, StopSound will be the only way to stop those sounds.
StopChannel
void StopChannel(short channelNum)
This function stops any sound currently playing in channelNum.
FindSound
short FindSound(short soundID)
FindSound searches all channels for soundID. If soundID is currently playing in any of the channels, the channel number is returned. Otherwise, -1 is returned.
SetChannelAvailability marks channelNum as being either available or unavailable for sounds looking for an empty channel. When you call PlaySound or PlaySound2 with kFindEmptyChannel as the playType, the function will attempt to play the sound in the first unused channel it finds, if that channel is marked as available. By default, all channels are marked as available.
You can use this function to "reserve" a channel for specific sounds, such as a gun shot sound that is played a lot. The only way to play a sound in a channel marked as unavailable is to use kPlaySoundInChannel or kReplaceSameSound as your PlayType when calling PlaySound.
SetChannelVolume
void SetChannelVolume(short channelNum, short newVolume)
This function sets the volume of the sound currently playing in channelNum. Subsequent sounds played in that channel will not be affected by this call, since their volume is determined by PlaySound. The newVolume parameter specifies the volume, where 0 is silence and 256 is full or natural volume. Any values above 256 will "overdrive" the sound, making it louder than normal, at the risk of distored playback.
If you make use of the stereoPosition parameter of PlaySound2 or call SetStereoPosition, you should consider using a maximum volume of 128 for all sounds, instead of 256. See SetStereoPosition for more information.
SetStereoPosition
void SetStereoPosition(short channelNum, short stereoPosition)
This function sets the stereo position of the sound currently playing in channelNum. Subsequent sounds played in that channel will not be affected by this call, since their stereo position is set by PlaySound. The stereoPosition parameter is a value between -256 and 256, where -256 plays all sound out the left speaker, 256 plays all sound out the right, and 0 centers the sound in the middle.
Note: this function works by "overdriving" the speaker that has more sound that the other one. For instance, if the sound is coming completely out of the right speaker, the right volume will be 512 (twice the normal volume), while the left volume is 0. Many sounds will become distored when they are played above their normal volume of 256. To avoid distored sounds, simply use a maximum volume of 128 when calling SetChannelVolume or PlaySound2. That way, when the sound volume for a particular speaker is raised above the normal volume to achieve stereo effects, its volume will reach a maximum of 256, which won't result in any distortion. If a maximum volume of 128 is too low, you can set the system sound volume higher with SetSystemVolume. Naturally, if you use 128 as your maximum volume, you should use it for all sounds, whether they make use of the stereo features or not, so that all sounds will be played at a consistent volume.
SetStereoMode
void SetStereoMode(Boolean mode)
Some Macintoshes with internal speakers will only play sounds passed to the left speaker. This means that if you set the stereo position of a sound to come completely from the right speaker, it will not sound at all on these Macs. Likewise, if a sound is to be played mostly from the right speaker and a little from the left, it will sound very faint on these Macs. SetStereoMode alleviates this problem by allowing you to turn stereo on or off. When you turn it off by passing false as the mode parameter, all sound is played in mono, regardless of whatever calls are made SetStereoPosition, or what you pass as the stereoPosition parameter to PlaySound2. This means your sounds will be heard on all Macintoshes.
Typically, you would provide a preferences item that allows users to switch between stereo and mono sound. Then you simply call SetStereoMode with a value of true to turn stereo on, or a value of false to turn it off. The stereo mode is on by default, and its value remains the same even if you dispose your channels and sounds and recreate them.
GetStereoPositionOfSprite
short GetStereoPositionOfSprite(SpritePtr srcSpriteP, Rect *theRect)
This function simply calls GetStereoPositionOfColumn, passing it the middle of the srcSpriteP as the col. You might want to pass the address of spriteWorldP->backRect as the theRect parameter if your game is a non-scrolling game, or the visScrollRect if the game is a scrolling game. You'd also probably want to make the volume softer in proportion to how far the Sprite is from the visScrollRect.
GetStereoPositionOfColumn
short GetStereoPositionOfColumn(short col, Rect *theRect)
This is a utility function that makes it easier to get the stereo position of a Sprite or some other object. Simply pass the column of the Sprite or object you wish to get the stereo position of, as well as a rectangle defining the boundaries of the "stereo world". The value returned indicates the stereo position of col relative to its position in theRect and will be anywhere from -256 if the col is on the far left side of the rect to 256 if the col is at the far right side of the rect. You can pass the returned value to SetStereoPosition or PlaySound2.
